/*
 * util.h
 *
 *  Created on: 05/12/2008
 *      Author: fernando
 */

#ifndef UTIL_H_
#define UTIL_H_

#include <string>
#include <map>

#include "StreamException.h"

using std::string;
using std::map;
using core::StreamException;

/**
 * Pacote de utilitários.
 */
namespace util {

/**
 * Copia uma sequência de caracteres da string origem para a string destino
 * omitindo os espaços em branco no início e no fim da sequência.
 * <p>
 * Se as string origem e destino forem as mesmas o resultado é indefinido.
 *
 * @param origin
 * 			A string origem.
 * @param position
 * 			A posição inicial;
 * @param size
 * 			A quantidade de caractes lidos a partir da posição inicial. Se a
 * 			quantidade de caracteres superar a quantidade de caracteres
 * 			disponíveis para leitura na string origem serão retornados somente
 * 			estes caracteres disponíveis. Se a quantidade de caracteres for
 * 			negativa serão lidos os caracteres até o fim da string origem.
 * @param destination
 * 			A string destino, para onde os caracteres lidos devem ser escritos.
 */
void normalize_space(string& origin, int position, int size,
		string& destination);

/**
 * Grava um mapa em arquivo no formato chave=valor. Cada par de
 * chave=valor é salvo em um linha diferente.
 *
 * @param the_map
 * 			O mapa contendo pares de strings no formato chave=valor.
 * @param filename
 * 			Nome do arquivo destino.
 */
void dump_map(map<const string, string>& the_map, string filename)
		throw (StreamException);

/**
 * Carrega um mapa de um arquivo. Cada par chave=valor deve estar em uma linha
 * diferente. Espaços no início e no fim da chave e no início e no fim do valor
 * são omitidos.
 *
 * @param the_map
 * 			O mapa para onde os pares chave=valor serão copiados.
 * @param filename
 * 			Nome do arquivo destino contendo pares de strings no formato
 * 			chave=valor.
 */
void load_map(map<const string, string>& the_map, string filename)
		throw (StreamException);

}

#endif /* UTIL_H_ */
